<!doctype HTML>
<html>
<head><title>MungeTLS README</title></head>
<body>
<h1>MungeTLS</h1>
<h3>A library + sample web server for testing TLS 1.0, 1.1, and 1.2</h3>

<h2>Installation/running instructions</h2>

<p>Make sure you have <a href="http://msdn.microsoft.com/en-us/library/bfsktky3.aspx">makecert.exe</a> in your PATH somewhere. It comes with the <a href="http://msdn.microsoft.com/en-us/windows/hardware/hh852363.aspx">Windows SDK</a>.</p>

<p>certutil.exe should already be in your PATH, since it comes with Windows.</p>

<p>Run <code>misc\add_certs.cmd</code><br />
This adds some test certificates for the server. Accept whatever warnings it pops up<br />
You should delete the certificates later by running <code>misc\del_certs.cmd</code>.</p>

<p>Add the following line to your hosts file (on Windows, <code>%windir%\system32\drivers\etc\hosts</code>):<br />
<code>127.0.0.1 mtls-test</code></p>

<p>Run <code>exe\MungeTLS.exe</code></p>

<p>Now see it in action: open a web browser and navigate to <a href="https://mtls-test:8879/">https://mtls-test:8879/</a>.</p>

<p>TIP: to make things go faster, redirect the output to a log file.</p>


<h2>Writing apps that use MungeTLS</h2>

<p>Read <code>inc\MungeTLS.h</code>, especially the definition of <code>ITLSServerLister</code>. This is the contract that the calling app has to implement.</p>

<p>To see how to drive the TLS negotiation and act as a TLS server, it is best to read <code>exe\main.cpp</code>, a sample caller that exercises all of the features.</p>


<h2>Porting notes</h2>

<p>If you are trying to use a different security library (not Windows' CryptoAPI) or platform, you will need to search for "<code>PLATFORM:</code>" in the source tree and implement all of the indicated functions and classes. As an example, <code>plat_lib_windows</code> does this.</p>


<h2>Build instructions</h2>

<p>Open a Visual Studio 2010 or 2012 command prompt and just type <code>nmake</code> in the trunk folder. It's been tested with both 2010 and 2012.</p>


<h2>Netmon Configuration</h2>

<p>The application can work with <a href="http://www.microsoft.com/en-us/download/details.aspx?id=4865">Netmon 3.4</a> to produce Netmon capture files with the unecrypted traffic, for very easy inspection. At compile-time, if <code>NMAPI.dll</a> is found in the PATH, the application will compile in Netmon support. Then at runtime, it again checks for <code>NMAPI.dll</code> before trying to invoke any Netmon functionality, allowing you to distribute the binary to someone who doesn't have it installed.</p>

<p>To process and display the capture properly, you will need to configure Netmon to pick up the parser file at <code>misc\mungetls.npl</code>.</p>

<ol>
<li>In Netmon, go to your parser options and edit your current profile (might need to create a clone of it, if it's one of the built-in ones) and add the <code>misc</code> dir as part of your search path.</li>
<li>Also in your parser profile properties, make note of a directory that looks something like <code>C:\Users\knutaf\AppData\Roaming\Microsoft\Network Monitor 3\5E0BBCD3-BB76-444D-815C-40299B3FF858</code>. In that folder, edit <code>my_sparsers.npl</code> and add the following line to it:<br />
<code>include "mungetls.npl"</code></li>
</ol>


<h2>Code reading suggestions</h2>

<p>Read the RFCs:<br />
<a href="http://www.ietf.org/rfc/rfc2246.txt">TLS 1.0</a><br />
<a href="http://www.ietf.org/rfc/rfc5246.txt">TLS 1.2</a></p>

<p>Start with <code>inc\MungeTLS.h</code>. The entrypoint is in <code>exe\main.cpp</code>. Read <code>lib\MungeTLS.cpp</code> and spiral outwards as needed. All platform specific code is in <code>plat_lib_windows\</code> and <code>exe\</code>.</p>
</body>
</html>
